Inside Macintosh: QuickTime /

Chapter 3 - Image Compression Manager / Image Compression Manager Reference

Image Compression Manager Functions / Working With Sequences

CompressSequenceBegin

Your application calls the CompressSequenceBegin function to signal the beginning of the process of compressing a sequence of frames. The Image Compression Manager prepares for the sequence-compression operation by reserving appropriate system resources. You must call this function before calling the CompressSequenceFrame function, which is described in the next section.

pascal OSErr CompressSequenceBegin (ImageSequence *seqID,
                                    PixMapHandle src, 
                                    PixMapHandle prev, 
                                    const Rect *srcRect, 
                                    const  Rect *prevRect, 
                                    short colorDepth, 
                                    CodecType cType,
                                    CompressorComponent codec,
                                    CodecQ spatialQuality,
                                    CodecQ temporalQuality, 
                                    long keyFrameRate,
                                    CTabHandle clut, 
                                    CodecFlags flags,
                                    ImageDescriptionHandle desc);

seqID

Contains a pointer to a field to receive the unique identifier for this sequence. You must supply this identifier to all subsequent Image Compression Manager functions that relate to this sequence.

src

Contains a handle to a pixel map that will contain the image to be compressed. The image must be stored in a pixel map structure.

prev

Contains a handle to a pixel map that will contain a previous image. The compressor uses this buffer to store a previous image against which the current image (stored in the pixel map referred to by the src parameter) is compared when performing temporal compression. This pixel map must be created at the same depth and with the same color table as the source image. The compressor manages the contents of this pixel map based upon several considerations, such as the key frame rate and the degree of difference between compared images. If you want the compressor to allocate this pixel map or if you do not want to
perform temporal compression (that is, you have set the value of the temporalQuality parameter to 0), set this parameter to nil.

You can set or change the previous image buffer for an active sequence by calling the SetCSequencePrev function. You can obtain a pointer to a pixel map that was allocated by the compressor by calling the GetCSequencePrevBuffer function. See "Changing Sequence-Compression Parameters," which begins on page 3-113, for information about these functions.

srcRect

Contains a pointer to a rectangle defining the portion of the image to compress. The compressor applies this rectangle to the image stored in the buffer referred to by the src parameter.

prevRect

Contains a pointer to a rectangle defining the portion of the previous image to use for temporal compression. The compressor uses this portion of the previous image as the basis of comparison with the current image. The compressor ignores this parameter if you have not provided a buffer for previous images. This rectangle must be the same size as the source rectangle, which is specified with the srcRect parameter.

You can set or change the rectangle used with the previous image buffer for an active sequence by calling the SetCSequencePrev function. See "Changing Sequence-Compression Parameters," which begins on page 3-113, for information about this function.

colorDepth

Specifies the depth at which the sequence is likely to be viewed. Compressors may use this as an indication of the color or grayscale resolution of the compressed images. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor information structure returned by the GetCodecInfo function (described on page 3-65).

cType

Specifies a compressor type. You must set this parameter to a
valid compressor type (see Table 3-3 on page 3-64 for a list of the available compressor types).

codec

Specifies a compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first compressor of the specified type

bestSpeedCodec

Choose the fastest compressor of the specified type

bestFidelityCodec

Choose the most accurate compressor of the specified type

bestCompressionCodec

Choose the compressor that produces the smallest resulting data

You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation.

If you set the codec parameter to anyCodec, the Image Compression Manager chooses the first compressor it finds of the specified type.

spatialQuality

Specifies the desired compressed image quality. See "Compression Quality Constants" beginning on page 3-57 for available values. You can change the value of this parameter for an active sequence by calling the SetCSequenceQuality function (described on page 3-114).

temporalQuality

Specifies the desired sequence temporal quality. This parameter governs the level of compression you desire with respect to information between successive frames in the sequence. Set this parameter to 0 to prevent the compressor from applying temporal compression to the sequence. See "Compression Quality Constants" beginning on page 3-57 for other available values.

You can change the value of this parameter for an active sequence by calling the SetCSequenceQuality function (described on page 3-114).

keyFrameRate

Specifies the maximum number of frames allowed between key frames. Key frames provide points from which a temporally compressed sequence may be decompressed. Use this parameter to control the frequency at which the compressor places key frames into the compressed sequence. The compressor determines the optimum placement for key frames based upon the amount of redundancy between adjacent images in the sequence. Consequently, the compressor may insert key frames more frequently than you have requested. However, the compressor never places fewer key frames than is indicated by the setting of the keyFrameRate parameter. The compressor ignores this parameter if you have not requested temporal compression (that is, you have set the temporalQuality parameter to 0). If you pass in 0 in this parameter, this indicates that there are no key frames in the sequence. If you pass in any other number, it specifies the number of non-key frames between key frames. Set this parameter to 1 to specify all key frames, to 2 to specify every other frame as a key frame, to 3 to specify every third frame as a key frame, and so forth.

Your application may change the key frame rate for an active sequence by calling the SetCSequenceKeyFrameRate function (described beginning on page 3-115). See "Defining Key Frame Rates" on page 3-47 for more information about key frames.

clut

Contains a handle to a custom color lookup table. Your program may use this parameter to indicate a custom color lookup table to be used with this image. If the value of the colorDepth parameter is less than or equal to 8 and the custom color lookup table is different from that of the source pixel map (that is, the ctSeed field values differ in the two pixel maps), the compressor remaps the colors of the image to the custom colors. If you set the colorDepth parameter to 16, 24, or 32, the compressor stores the custom color table with the compressed image. The compressor may use the table to specify the best colors to use when displaying the image at lower bit depths. The compressor ignores the clut parameter when colorDepth is set to 33, 34, 36, or 40. If you set this parameter to nil, the compressor uses the color lookup table from the source pixel map.

flags

Contains flags providing further control information. See "Image Compression Manager Function Control Flags," which begins on page 3-58, for information about CodecFlags fields. You must set either the value of the codecFlagUpdatePrevious flag or the codecFlagUpdatePreviousComp flag to 1 (be sure to set unused flags to 0). The following flags are available for this function:

codecFlagUpdatePrevious

Controls whether the compressor updates the previous image during compression. This flag is only used with sequences that are being temporally compressed. If you set this flag to 1, the compressor copies the current frame into the previous frame buffer at the end of frame compression.

codecFlagUpdatePreviousComp

Controls whether the compressor updates the previous image buffer with the compressed image. This flag is only used with temporal compression and is similar to
the codecFlagUpdatePrevious flag. As with the codecFlagUpdatePrevious flag, if you set this flag to 1, the compressor updates the previous frame buffer at the end of frame compression. However, this flag causes the Image Compression Manager to update the frame buffer using an image obtained by decompressing the results of the most recent compression operation, rather than the source image, which may give better results at the expense of taking more time.

codecFlagWasCompressed

Indicates to the compressor that the image to be compressed has been compressed before. This information may be useful to compressors that can compensate for the image degradation that may otherwise result from repeated compression and decompression of the same image. Set this flag to 1 to indicate that the image was previously compressed. Set this flag to 0 if the image was not previously compressed.

desc

Contains a handle that is to receive a formatted image description structure. The Image Compression Manager resizes this handle for the returned image description structure. Your application should store this image description with the compressed sequence.
During the compression operation, the Image Compression Manager and the compressor component update the contents of this image description. Consequently, you should not store the image description until the sequence has been completely processed.

RESULT CODES

noErr	0	No error
paramErr	-50	Invalid parameter specified
memFullErr	-108	Not enough memory available
noCodecErr	-8961	The Image Compression Manager could not find the specified compressor
codecConditionErr	-8972	Component cannot perform requested operation